/*
 * Copyright 2011 Mark Davidson.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */

package org.dctmcommons;

import java.util.Date;
import java.util.List;
import java.util.Map;


import com.documentum.fc.client.IDfCollection;
import com.documentum.fc.client.IDfSession;
import com.documentum.fc.common.DfException;
import com.documentum.fc.common.IDfId;

/**
 * Query-related helper methods.
 */
public interface IQueryHelper {
	
    /**
     * Close a collection, swallowing any thrown exception quietly.
     * @param collection The collection
     */
	public void closeCollectionQuietly(IDfCollection collection);

    /**
     * Close a collection.
     * @param collection The collection
     * @throws DfException The repository exception
     */
    public void closeCollection(IDfCollection collection) throws DfException;
    
    /**
     * Executes a server method.
     * @param session The repository session
     * @param methodName The method name
     * @param methodArgs The method arguments
     * @throws DfException The repository exception
     * @deprecated Use {@link IMethodBuilder} instead
     */
    public void runMethod(IDfSession session,
    					  String methodName,
    					  Map<String, String> methodArgs) throws DfException;
    
	/**
	 * Performs an update query.
	 * @param session The session
	 * @param dql The DQL string
	 * @param queryType The query type
	 * @throws DfException The repository exception
	 */
	public void updateQuery(IDfSession session,
						    String dql,
						    int queryType) throws DfException;

	/**
	 * Performs a count query for the specified qualification string.
	 * @param session The session
	 * @param qualification The qualification
	 * @return The count
	 * @throws DfException The repository exception
	 */
	public int queryForCount(IDfSession session,
							 String qualification) throws DfException;

	/**
	 * Executes a query, returning the resulting results collection. Please
	 * remember to close the results collection in a finally block.
	 * @param session The repository session
	 * @param dql The DQL string
	 * @param queryType The query type
	 * @return The results collection
	 * @throws DfException The repository exception
	 */
	public IDfCollection query(IDfSession session,
							   String dql,
							   int queryType) throws DfException;
	
	/**
	 * Executes a query, invoking a callback object for each retrieved row in
	 * the results collection.
	 * @param session The repository session
	 * @param dql The DQL string
	 * @param queryType The query type
	 * @param callback The callback object
	 * @throws DfException The repository exception
	 */
	public void query(IDfSession session,
					  String dql,
					  int queryType,
					  ITypedObjectCallback callback)
		throws DfException;

	/**
	 * Executes a query, returning the results as a {@link List} of
	 * {@link Map} objects.
	 * @param session The repository session
	 * @param dql The DQL string
	 * @param queryType The query type
	 * @return The results as a List} of {@link Map} objects
	 * @throws DfException Repository exception
	 */
	public List<Map<String, Object>> queryForListOfMaps(
										IDfSession session,
										String dql,
										int queryType)
		throws DfException;

	/**
	 * Fetches single string values (e.g. object_name, owner_name, etc).
	 * @param session The session
	 * @param dql The SQL string
	 * @param queryType The query type
	 * @return The results
	 * @throws DfException The repository exception
	 */
	public String[] queryForSingleStringValues(IDfSession session,
											   String dql,
											   int queryType)
		throws DfException;

	/**
	 * Fetches a single string attribute value.
	 * @param session The session
	 * @param dql The DQL string
	 * @param queryType The query type
	 * @return The string value
	 * @throws DfException The repository exception
	 */
	public String queryForSingleStringValue(IDfSession session,
											String dql,
											int queryType) throws DfException;

	/**
	 * Fetches a repeating string attribute value.
	 * @param session The session
	 * @param dql The DQL string
	 * @param queryType The query type
	 * @return The string value(s)
	 * @throws DfException The repository exception
	 */
	public String[] queryForRepeatingStringValue(IDfSession session,
												 String dql,
												 int queryType)
		throws DfException;

	/**
	 * Fetches a single int attribute value.
	 * @param session The session
	 * @param dql The DQL string
	 * @param queryType The query type
	 * @return The int value
	 * @throws DfException The repository exception
	 */
	public int queryForSingleIntValue(IDfSession session,
									  String dql,
									  int queryType) throws DfException;

	/**
	 * Fetches a repeating int attribute value.
	 * @param session The session
	 * @param dql The DQL string
	 * @param queryType The query type
	 * @return The int value(s)
	 * @throws DfException The repository exception
	 */
	public Integer[] queryForRepeatingIntValue(IDfSession session,
											   String dql,
											   int queryType)
		throws DfException;

	/**
	 * Fetches a single boolean attribute value.
	 * @param session The session
	 * @param dql The DQL string
	 * @param queryType The query type
	 * @return The boolean value
	 * @throws DfException The repository exception
	 */
	public boolean queryForSingleBooleanValue(IDfSession session,
											  String dql,
											  int queryType) throws DfException;

	/**
	 * Fetches a repeating boolean attribute value.
	 * @param session The session
	 * @param dql The DQL string
	 * @param queryType The query type
	 * @return The boolean value(s)
	 * @throws DfException The repository exception
	 */
	public Boolean[] queryForRepeatingBooleanValue(IDfSession session,
												   String dql,
												   int queryType)
		throws DfException;

	/**
	 * Fetches a single double attribute value.
	 * @param session The session
	 * @param dql The DQL string
	 * @param queryType The query type
	 * @return The double value
	 * @throws DfException The repository exception
	 */
	public double queryForSingleDoubleValue(IDfSession session,
											String dql,
											int queryType) throws DfException;

	/**
	 * Fetches a repeating double attribute value.
	 * @param session The session
	 * @param dql The DQL string
	 * @param queryType The query type
	 * @return The double value(s)
	 * @throws DfException The repository exception
	 */
	public Double[] queryForRepeatingDoubleValue(IDfSession session,
												 String dql,
												 int queryType)
		throws DfException;

	/**
	 * Fetches a single id attribute value.
	 * @param session The session
	 * @param dql The DQL string
	 * @param queryType The query type
	 * @return The id value
	 * @throws DfException The repository exception
	 */
	public IDfId queryForSingleIdValue(IDfSession session,
									   String dql,
									   int queryType) throws DfException;

	/**
	 * Fetches a repeating id attribute value.
	 * @param session The session
	 * @param dql The DQL string
	 * @param queryType The query type
	 * @return The id value(s)
	 * @throws DfException The repository exception
	 */
	public IDfId[] queryForRepeatingIdValue(IDfSession session,
											String dql,
											int queryType) throws DfException;

	/**
	 * Fetches a single id attribute value.
	 * @param session The session
	 * @param dql The DQL string
	 * @param queryType The query type
	 * @return The id value
	 * @throws DfException The repository exception
	 */
	public String queryForSingleIdValueAsString(IDfSession session,
												String dql,
												int queryType)
		throws DfException;

	/**
	 * Fetches a repeating id attribute value.
	 * @param session The session
	 * @param dql The DQL string
	 * @param queryType The query type
	 * @return The id value(s)
	 * @throws DfException The repository exception
	 */
	public String[] queryForRepeatingIdValueAsString(IDfSession session,
													 String dql,
													 int queryType)
		throws DfException;

	/**
	 * Fetches a single date attribute value.
	 * @param session The session
	 * @param dql The DQL string
	 * @param queryType The query type
	 * @return The date value
	 * @throws DfException The repository exception
	 */
	public Date queryForSingleDateValue(IDfSession session,
										String dql,
										int queryType) throws DfException;

	/**
	 * Fetches a repeating date attribute value.
	 * @param session The session
	 * @param dql The DQL string
	 * @param queryType The query type
	 * @return The date value(s)
	 * @throws DfException The repository exception
	 */
	public Date[] queryForRepeatingDateValue(IDfSession session,
											 String dql,
											 int queryType) throws DfException;

}